home *** CD-ROM | disk | FTP | other *** search
/ Amiga News 95 / Amiga News 95.iso / dpat / dpat49 / reqtools.lzh / ReqTools / README < prev    next >
Text File  |  1992-03-08  |  13KB  |  307 lines
  1.  
  2.                       **********************************
  3.  
  4.                           reqtools.library
  5.  
  6.                           The requester toolkit.
  7.  
  8.                           Release 1.0d
  9.  
  10.                           (c) 1991/1992 Nico François
  11.  
  12.                       **********************************
  13.  
  14.  
  15.    First of all read the DISTRIBUTION file for information on... er well...
  16. distribution :-)
  17.  
  18.    If you have suggestions or remarks about ReqTools, or if you find any
  19. bugs, please let me know.
  20.  
  21.    Write to the following address:
  22.  
  23.                                 Nico François
  24.                                 Corbielaan 13
  25.                                 B-3060 Bertem
  26.                                 BELGIUM
  27.  
  28.  
  29. Contents
  30. ========
  31.  
  32. 1. An introduction
  33.  
  34. 2. Features
  35.  
  36. 3. Installation
  37.  
  38. 4. Using reqtools.library
  39.  
  40.  
  41. 1. An introduction
  42. ==================
  43.  
  44.     reqtools.library is a standard Amiga shared, runtime library.  The purpose
  45. of ReqTools is to make it a lot quicker and easier to build standard requesters
  46. into your programs.  ReqTools is designed with Commodore's style guidelines in
  47. mind, all requesters have the look-and-feel of AmigaDOS Release 2.
  48.  
  49.     If you use ReqTools in your programs you do not have to worry about
  50. requesters too much.  You'll have a lot more time to concentrate on the
  51. really important stuff your program does.
  52.  
  53.     The library has been inspired by req.library (by Colin Fox & Bruce Dawson)
  54. and Commodore's own asl.library.  You will find it shares a lot of the
  55. features with these two libraries, while it has some additional ones as well.
  56. While asl.library was great in look-and-feel I felt it lacked quite a bit in
  57. the power department.  This power _is_ mostly available in req.library, but
  58. this doesn't fit in too well with AmigaDOS Release 2.  So the idea for a new
  59. requester library was born.
  60.  
  61.     I tried to make all requesters in ReqTools very powerful, easy to use and 
  62. with a very nice new-look 3D interface.  Efficiency was also considered very
  63. important.  The 2.0 version of the library is about 20K large.  I'm sure you
  64. will agree this is not too much considering what ReqTools offers.
  65.  
  66.     ReqTools features the following requesters:  a query requester, a string
  67. requester, a number requester, a file requester, a font requester and a
  68. palette requester.
  69.  
  70.  
  71. 2. Features
  72. ===========
  73.  
  74.    The requesters have following features:
  75.  
  76.    All requesters:
  77.  
  78.     o have a pixel-perfect Workbench 2.0 3D look, also on Kickstart 1.3.
  79.     o adjust to interlaced screens and to the screen's font (rtEZRequest,
  80.       rtGetLong, rtGetString) or to any fixed-width font if the screen's font
  81.       is proportional (rtPaletteRequest, rtFileRequest or rtFontRequest).
  82.     o can appear under the mouse pointer, centered on the
  83.       screen/in a window or at the top left of the screen/a window.
  84.     o can be used asynchronously.
  85.     o check pr_WindowPtr of your process is to find the screen they should
  86.       appear on (can be overridden).
  87.     o use tags for maximum future extendibility.  All standard 2.0 tags are
  88.       supported (like TAG_SKIP, TAG_MORE, etc.).
  89.     o bring the screen they appear on to the front.  The screen that was
  90.       in front previously will be put in front again when the requester
  91.       finishes (if it is still open).
  92.     o will always appear in the visible portion of the screen (support of
  93.       virtual screens).
  94.     o are extensively tested using enforcer and mungwall debugging tools.
  95.  
  96.    rtEZRequest, the query requester:
  97.  
  98.     o easy keyboard shortcuts:
  99.       - Left Amiga V and Left Amiga B (like the standard requesters).
  100.       - Y for positive response.
  101.       - N, R, Esc for negative response.
  102.       - Return can also be used as a shortcut and can be
  103.         associated with any response.  The gadget in question
  104.         will have its text printed bold.
  105.         Default response for Return is the positive response.
  106.       - buttons give visual feedback when keyboard shortcuts
  107.         are used.
  108.       - keyboard shortcuts can be canceled by pressing Shift
  109.         before releasing the key.
  110.     o number of responses only limited by screen width.
  111.     o allows for multiple lines of text.
  112.     o text can be centered in requester (great for about requesters).
  113.     o supports the use of 'printf' formatting codes in text
  114.       and in responses.
  115.     o can be terminated by IDCMP events.
  116.  
  117.    rtFileRequest, the file requester:
  118.  
  119.     o similar in use and look-and-feel as Asl file requester.
  120.     o buffers directories in memory.
  121.     o files and directories can be added or removed from the buffer
  122.       by the calling program.
  123.     o can be put in save mode, disabling double-clicks and asking you if
  124.       directories that can't be found (entered manually) should be created.
  125.     o optional callback hook for verification of files before they are
  126.       added to the buffer.
  127.     o supports multiple selection of files and optionally of directories.
  128.     o when multi-select is on All, Clear and Match.. buttons are available.
  129.       All selects, and Clear unselects all files.  Match.. brings up a
  130.       requester where the user can enter a pattern to select files.
  131.     o can be used as a directory requester (showing no files).
  132.     o optional pattern gadget to match files on.
  133.     o shows all devices (with volume names) and all assigns made.
  134.     o supports TABCYCLE under 2.0
  135.     o pattern matching supports _ALL_ AmigaDOS 2.0 patterns.
  136.  
  137.    rtFontRequest, the font requester:
  138.  
  139.     o buffers all fonts in memory.
  140.     o shows sample of font you click on.
  141.     o can be also be used to select the font's style.
  142.     o supports color fonts, can change the screen's palette.
  143.     o supports scaled fonts (AmigaOS Release 2 only).
  144.     o optional callback hook for verification of fonts before they are
  145.       added to the buffer.
  146.     o supports TABCYCLE under 2.0
  147.  
  148.    rtPaletteRequest, the palette requester:
  149.  
  150.     o features Copy, Swap and Spread functions.
  151.     o current values of red, green and blue are displayed.
  152.     o returns the selected color.
  153.  
  154.    rtGetLong, the long integer requester:
  155.  
  156.     o width of requester can be set by caller.
  157.     o a minimum and maximum can be supplied and will be displayed
  158.       in the requester.
  159.     o a value to show up when the requester appears can be supplied.
  160.  
  161.    rtGetString, the string requester:
  162.  
  163.     o width of requester can be set by caller.
  164.     o a string to show up when the requester appears can be supplied.
  165.  
  166.  
  167. 3. Installation
  168. ===============
  169.  
  170.    To install reqtools.library copy it to your Libs: directory by hand, or
  171. run the installation script 'Install' (by using 'Execute' from the Shell or
  172. by double-clicking its icon).
  173.  
  174.    reqtools.library is provided in two versions (that are 100% equivalent):
  175. one for Kickstart 1.2 (or higher) and one for Kickstart 2.0 and higher.
  176.  
  177.    The version for Kickstart 2.0 uses 2.0 ROM functions for stuff like
  178. pattern matching, parsing tags, the 3D look, while a lot in the Kickstart 1.3
  179. version is emulated.  It is therefore suggested you use the 2.0 version of
  180. the library if you have Kickstart 2.0 in ROM.
  181.  
  182.  
  183. 4. Using reqtools.library
  184. =========================
  185.  
  186.    If you are a C programmer all you need to do is include the correct
  187. headers and open reqtools.library. After that you can use the functions in
  188. the library as if they were C functions. If your program quits it must of
  189. course close the library again.  See 'demo.c' for an example.
  190.  
  191.    If you are using SAS/C 5.10a and you don't want to use pragmas, or if you
  192. are using version 4.0 or lower, you must link with LIB:reqtools.lib (small
  193. code) or LIB:reqtoolsnb.lib (large code).
  194.  
  195.    From ReqTools 1.0c onwards Dice C is also supported.  You can find two
  196. libraries to link with in the dlib directory.  Link with reqtoolss.lib
  197. (standard args) or reqtoolssr.lib (registerized args).
  198.  
  199.    From ReqTools 1.0d onwards interfaces to Modula-2 and to Aztec C are also
  200. included.  You can find the files in the Modula2 (with documentation) and
  201. Aztec directories.
  202.  
  203.    Note that the functions allowing a variable number of arguments can't
  204. be called using pragmas.  So if you use these you must always link with
  205. LIB:reqtools.lib or LIB:reqtoolsnb.lib.
  206.  
  207.    Assembly programmers should also include the correct files and open
  208. reqtools.library.  To call a function they must load A6 with the library base,
  209. put the arguments in the appropriate registers and jump to the library vector
  210. offset of the function they want to call.
  211.  
  212.    All library functions are explained in the autodoc file 'reqtools.doc'.
  213.  
  214.                                                        Enjoy.
  215.  
  216.  
  217.                                LIBRARY HISTORY:
  218.  
  219. *****************************************************************************
  220. RELEASE 1.0 (Library version 37.556 [1.3] - 37.670 [2.0])
  221.  
  222.     First release.
  223.  
  224. *****************************************************************************
  225. RELEASE 1.0a (Library version 37.557 [1.3] - 37.673 [2.0])
  226.  
  227.     Fixed two minor bugs:
  228.       - if a directory could not be found and you re-invoked the file
  229.         requester it wouldn't check the directory again.
  230.       - devices like PRT:, CON:, etc. now no longer show up in the device
  231.         list of the 2.0 file requester.
  232.  
  233. *****************************************************************************
  234. RELEASE 1.0b (Library version 37.566 [1.3] - 37.678 [2.0])
  235.  
  236.     Fixed bug: entering a pattern when a file requester's directory was
  237.       invalid could cause a crash.
  238.     rtGetString() and rtGetLong() 2.0 requester windows no longer have close
  239.       gadgets.
  240.     Font requester entries are "release verify" instead of "immediate".
  241.     If no minimum or maximum is given for the GetLong requester it will not
  242.       be displayed (1.0 and 1.0a displayed MAXINT or MININT).
  243.     Minor cosmetic adjustments to file, font and palette requesters.
  244.     Oberon interface to the library included.
  245.  
  246. *****************************************************************************
  247. RELEASE 1.0c (Library version 37.592 [1.3] - 37.718 [2.0])
  248.  
  249.     Boopsi dispatch function for rtEZRequestA() buttons optimized (ReqTools
  250.       for Kickstart 2.0).  Occasional flicker just about eliminated.
  251.     Enlarged buttons a bit in rtGetLongA(), rtGetStringA() and the file, font
  252.       and palette requesters.
  253.     Width of scroller gadget in file requester window increased.
  254.     File string gadget is cleared when 'All' or 'Match..' is used.  This
  255.       wasn't done before and could result in unexpected multi-select results.
  256.     Visual feedback for keyboard shortcuts improved (rtEZRequestA()).  Button
  257.       stays depressed as long as the key in question is held down, but still
  258.       for a minumum of 1/10 sec.  New feature:  shortcuts can be canceled by
  259.       pressing Shift before releasing the key.
  260.     Minor bug fix: keyboard shortcuts V and B now really only work together
  261.       with the Left Amiga key.  Used to work without the qualifier.
  262.     rtEZRequestA(), rtGetLongA() and rtGetStringA() will no longer call the
  263.       DOS function Delay(), so they may from now on be called by tasks.
  264.       Every ReqTools requester, except the file and font requesters (they use
  265.       DOS for obvious reasons), can be called from a task.
  266.     EZRequest with only one button now responds to the Return key, whether
  267.       EZREQF_NORETURNKEY is set or not.
  268.     Fixed small bug in libraries/reqtools.i include file.  rtfi_Hook and
  269.       rtfo_Hook were followed by a ; and this could lead to problems.
  270.     Libraries (reqtoolss.lib and reqtoolssr.lib) for Dice C included.
  271.     Pre-release (0.91ß) of RTPatch patcher program included.
  272.  
  273. *****************************************************************************
  274. RELEASE 1.0d (Library version 37.600 [1.3] - 37.726 [2.0])
  275.  
  276.     rtEZRequestA(), rtGetStringA() and rtGetLongA() now switch the processor
  277.       stack to ensure sufficient stack space for the function to succeed.
  278.     Fixed bug in rtGetLong() requester in 2.0 version of ReqTools.  Used to
  279.       return TRUE and a random value if the user pressed Ok when the integer
  280.       gadget was empty.
  281.     File requester is somewhat larger by default.
  282.     Improved automatic requester resizing (if requester would become too big
  283.       for the screen).
  284.     File requester (in save mode) no longer asks "Create drawer?" when you
  285.       entered a drawer string containing a non-existing volume (e.g. 'FOO:').
  286.     Entries in file requester are now sorted immediately when you select the
  287.       slider gadget and not when you release it (1.3 version of ReqTools).
  288.     Latest revision of Oberon interface included.
  289.     Modula-2 interface to the library included.
  290.     Aztec C interface to the library included.
  291.  
  292. *****************************************************************************
  293.  
  294. reqtools.library written by Nico François (Yes, Nico is my first name :-)
  295.                  thanks to Kai Bolay for writing the Oberon interface,
  296.                            Frank Lömker for writing the Modula-2 interface,
  297.                            Jan van den Baard for writing the Dice libraries,
  298.                            Martin Steppler for writing the Aztec C libraries,
  299.                            Federico Giannici for the useful suggestions.
  300.  
  301.  
  302. (c) 1991/1992 Nico François
  303.  
  304.                                    //
  305.                        Thanks to \X/ Amiga for being the best computer ever !
  306.  
  307.